home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 February: Technology Seed / Mac Tech Seed Feb '97.toast / OpenDoc 1.2b2c1 / OpenDoc / OpenDoc Utilities / Interfaces / ODDebug.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-01-01  |  6.1 KB  |  190 lines  |  [TEXT/MPS ]
  1. /*
  2.     File:        ODDebug.h
  3.  
  4.     Contains:    Useful debugging macros and functions.
  5.  
  6.     Owned by:    Jens Alfke
  7.  
  8.     Copyright:    © 1993 - 1996 by Apple Computer, Inc., all rights reserved.
  9.  
  10.     Change History (most recent first):
  11.  
  12.          <4>     9/17/96    RA        1315228: Added WASSERT_IS_PART_WRAPPER
  13.          <3>     5/24/96    jpa        1.1MRD: pragma internal eliminates NOPs.
  14.          <2>    .05.1996    NP        1352438: Add IsOptionKeyDown and
  15.                                     IsAnyKeyDown
  16.  
  17.     To Do:
  18. */
  19.  
  20. #ifndef _ODDEBUG_
  21. #define _ODDEBUG_
  22.  
  23. #ifndef _ODTYPES_
  24. #include "ODTypes.h"
  25. #endif
  26.  
  27.  
  28. #ifdef _OD_IMPL_SHARE_UTILS_
  29. #pragma import on
  30. #elif defined(PRAGMA_INTERNAL_SUPPORTED)
  31. #pragma internal on
  32. #endif
  33.  
  34. #ifdef __cplusplus
  35. extern "C" {
  36. #endif
  37.  
  38.  
  39. //==============================================================================
  40. // ODInitExceptions
  41. //==============================================================================
  42.  
  43. void ODInitExceptions( );
  44.  
  45. //==============================================================================
  46. // Misc
  47. //==============================================================================
  48.  
  49. ODBoolean IsThisKeyDown(ODUShort theKey);
  50. inline ODBoolean IsOptionKeyDown() {return IsThisKeyDown(0x3A);}
  51.  
  52. //==============================================================================
  53. // Debug Output
  54. //==============================================================================
  55.  
  56. enum DebugOutputMode {
  57.     kNoOutput,
  58.     kWriteToFile,
  59.     kWriteToDebugWindow,
  60.     kGenerateDebugStrs
  61. };
  62.  
  63. DebugOutputMode    GetOutputMode( );
  64. void            SetOutputMode( DebugOutputMode );
  65.  
  66.  
  67. //==============================================================================
  68. // Warnings
  69. //==============================================================================
  70.  
  71. // WARN has the same syntax as printf but produces a SysBreakStr.
  72. // Warnings are disabled (and generate no code) when ODDebug is off.
  73.  
  74. #define WARN    if(!ODDebug) ; else _Warn
  75.  
  76.  
  77. //==============================================================================
  78. // Assertions
  79. //==============================================================================
  80.  
  81. // These all cause a debugger break if the condition evaluates to false or 0.
  82. // Leading "W" is a Warning: it doesn't raise an exception.
  83. // Trailing "M" means special Message displayed instead of condition.
  84.  
  85. #ifndef __MWERKS__
  86.     #define _FIL_ ""            /* MPW puts entire pathnames in; yuk! */
  87. #else
  88.     #define _FIL_ __FILE__
  89. #endif
  90.  
  91. #define ASSERT( COND, ERR )    \
  92.     if(!ODDebug || (COND)) ; else _AssertionFailed( #COND, _FIL_, ERR )
  93. #define ASSERTM( COND, ERR, MSG )    \
  94.     if(!ODDebug || (COND)) ; else _AssertionFailed( #COND, _FIL_, ERR, MSG )
  95. #define WASSERT( COND )    \
  96.     if(!ODDebug || (COND)) ; else _AssertionFailed( #COND, _FIL_, 0)
  97. #define WASSERTM( COND, MSG )    \
  98.     if(!ODDebug || (COND)) ; else _AssertionFailed( #COND, _FIL_, 0, MSG)
  99.  
  100. // ASSERT_NOT_NULL causes a debugger break and an exception if the parameter
  101. // is NULL. Use this in functions that take a pointer as a parameter but do
  102. // not allow the parameter to be NULL.
  103. // Do **NOT** use this macro to make sure memory allocation succeeded! It
  104. // has no effect in non-debug builds. Use THROW_IF_NULL instead.
  105.  
  106. #define ASSERT_NOT_NULL(PARAM) \
  107.     ASSERT((PARAM)!=kODNULL, kODErrIllegalNullInput)
  108.  
  109. // WASSERT_IS_PART_WRAPPER (suggested by 1315228)
  110. // warn developers when they pass real ODPart* ptrs to APIs where
  111. // PartWrapper*s are called for instead.  Because the Shell is
  112. // special-cased as NULL, we need to account for that too.
  113.  
  114. #define WASSERT_IS_PART_WRAPPER( ev, rootPart )                                \
  115.     if(!ODDebug || (rootPart) == kODNULL || !(rootPart)->IsRealPart(ev) ) ;    \
  116.         else _Warn( "ODPart passed where ODPartWrapper expected." )
  117.  
  118. //==============================================================================
  119. // Logging
  120. //==============================================================================
  121.  
  122. // PRINT writes to the standard output via somPrintf if ODDebug is on. Use
  123. // SetOutputMode (or the ODDebug menu) to direct output to a file or to the
  124. // DebugWindow app.
  125.  
  126. #define PRINT    if(!ODDebug) ; else somPrintf
  127.  
  128. // LOG is like PRINT but can easily be turned on or off on a per-file basis.
  129. // To enable logging in a source file, you must redefine the symbol LOGGING
  130. // as "1" in that file, otherwise LOG statements will not be compiled. Make
  131. // sure to #undef the symbol before you re-#define it, as some compilers
  132. // won't redefine an already-defined symbol.
  133.  
  134. // PRINT and LOG statements do not generate any code if logging is off.
  135.  
  136. #define LOGGING 0        // Redefine as 1 in source file to enable logging
  137.  
  138. #define LOG        if(!ODDebug || !LOGGING) ; else somPrintf
  139.  
  140.  
  141. //==============================================================================
  142. // Safe Type-Casting
  143. //==============================================================================
  144.  
  145. /*    Use CAST as a safe way to cast a SOM object from one class to another.
  146.     For instance, if "o" is declared as an ODObject*, but your code knows
  147.     it's an ODPart*, you can say:
  148.             ODPart *part = CAST(o,ODPart);
  149.     If ODDebug is turned on, this will do a runtime check and cause an assertion
  150.     failure if o does not point to an ODPart (or subclass). Without ODDebug,
  151.     it degenerates into a simple C-style cast that generates no code.
  152.     
  153.     ASSERT_IS_A is similar to CAST but is used when you just want to assert
  154.     that the pointer points to the right kind of object.
  155. */
  156.  
  157. #if ODDebug
  158.     #define CAST(OBJ, CLASS)    ( (CLASS*)_Cast((OBJ), (somClassDataStructure*) &CLASS##ClassData,        \
  159.                                                         CLASS##_MajorVersion, CLASS##_MinorVersion) )
  160.     #define ASSERT_IS_A(OBJ,CLASS)    ( (void) CAST(OBJ,CLASS) )
  161. #else
  162.     #define CAST(OBJ, CLASS)    ( (CLASS*) (OBJ) )
  163.     #define ASSERT_IS_A(OBJ,CLASS)    /* */
  164. #endif
  165.  
  166.  
  167. //==============================================================================
  168. // Internal goop...
  169. //==============================================================================
  170.  
  171. void _Warn                ( char *fmt, ... );
  172. void _AssertionFailed    ( char *cond,  char *fileName,
  173.                             ODError, char *msg = kODNULL );
  174. #if ODDebug
  175. SOMObject* _Cast( SOMObject *obj, somClassDataStructure *cls, long major, long minor );
  176. #endif
  177.  
  178.  
  179. #ifdef __cplusplus
  180. }
  181. #endif
  182.  
  183. #ifdef _OD_IMPL_SHARE_UTILS_
  184. #pragma import off
  185. #elif defined(PRAGMA_INTERNAL_SUPPORTED)
  186. #pragma internal reset
  187. #endif
  188.  
  189. #endif /*_ODDEBUG_*/
  190.